---
title: 内容集合 API 参考
sidebar:
  label: 'astro:content'
i18nReady: true
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 6
---
import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro';

<p><Since v="2.0.0" /></p>

内容集合提供了 API 来配置和查询 `src/content/` 中的 Markdown 或 MDX 文档。有关功能和用法示例，请参考[内容集合指南](/zh-cn/guides/content-collections/)。

## 从 `astro:content` 导入

```js
import { 
  z,
  defineCollection,
  getCollection,
  getEntry,
  getEntries,
  reference,
  render,
 } from 'astro:content';
```

### `defineCollection()`

<p>

**类型：**`(input: CollectionConfig) => CollectionConfig`
<Since v="2.0.0" />
</p>

`defineCollection()` 是一个用于在 `src/content.config.*` 文件中配置集合的工具函数。

```ts title="src/content/config.js"
import { z, defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// 将定义的集合公开给 Astro
// 通过 `collections` 导出
export const collections = { blog };
```

这个函数接受以下属性：

#### `loader`

<p>

**Type:** <code>() => Promise&lt;Array&lt;\{ id: string, [key: string]: any }&gt; | Record&lt;string, Record&lt;string, any&gt;&gt;&gt; | <a href="/zh-cn/reference/content-loader-reference/#对象加载器-api">Loader</a></code>
<Since v="5.0.0" />
</p>

`loader` 是一个对象或函数，允许你从任何源加载数据到内容集合中，无论是本地还是远程数据。

更多有关示例请 [参考`内容集合`指南](/zh-cn/guides/content-collections/#定义集合-loader)。

#### `schema`

<p>

**类型：**<code>ZodType | (context: <a href="#schemacontext">SchemaContext</a>) => ZodType</code>
<Since v="2.0.0" />
</p>

`schema` 是一个可选的 Zod 对象，用于配置集合的文档 frontmatter 的类型和形状。每个值必须使用 [Zod 验证器](https://github.com/colinhacks/zod)

更多有关示例请 [参考`内容集合`指南](/zh-cn/guides/content-collections/#定义集合模式schema)。

### `reference()`

<p>

**类型：**`(collection: string) => ZodEffects<ZodString, { collection, id: string }>`<br />
<Since v="2.5.0" />
</p>

内容配置中的 `reference()` 函数，用于定义一个集合与另一个集合之间的关联，或者说“引用”。该函数接受一个集合名称，并将其转换为一个包含集合名称与引用 id 的对象。

此示例定义了从博客作者到 `authors` 集合的引用，以及到同一 `blog` 集合的相关文章数组的引用：

```ts
import { defineCollection, reference, z } from 'astro:content';
import { glob, file } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    // 通过 `id` 从 `authors` 集合中，引用单个作者
    author: reference('authors'),
    // 通过 `slug` 从 `blog` 集合中，引用相关帖子数组
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  loader: file("src/data/authors.json"),
  schema: z.object({ /* ... */ })
});

export const collections = { blog, authors };
```

在使用 `getEntry()` 或 `getEntries()` 的运行时环境下，对引用条目的有效性进行验证：

```astro title="src/pages/[posts].astro"
// 如果引用条目是无效的，那么将会返回 undefined。
const relatedPosts = await getEntries(blogPost.data.relatedPosts);
```

更多有关示例请 [参考`内容集合`指南](/zh-cn/guides/content-collections/#定义集合引用)。

### `getCollection()`

<p>

**类型：** `(collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]`
<Since v="2.0.0" />
</p>

`getCollection()` 是一个函数，用于通过集合名称检索内容集合条目列表。

默认情况下，它返回集合中的所有项目，并接受可选的 `filter` 函数来缩小条目属性。这允许你根据 `id` 或 frontmatter 值（通过 `data` 对象）查询集合中的某些项目。

```astro
---
import { getCollection } from 'astro:content';

// 获取 `src/content/blog/` 中的所有条目
const allBlogPosts = await getCollection('blog');

// 仅返回 frontmatter 中 `draft: true` 的条目
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---
```

更多有关示例请 [参考`内容集合`指南](/zh-cn/guides/content-collections/#查询集合)。

### `getEntry()`

<p>

**Type:** 
* `(collection: string, id: string) => Promise<CollectionEntry<collection> | undefined>`
* `({ collection: string, id: string }) => Promise<CollectionEntry<collection> | undefined>`
<Since v="2.5.0" />
</p>

`getEntry()` 是一个函数，通过集合名称和条目 `id` 检索单个集合条目。`getEntry()` 也可以用于获取引用条目以访问 `data` 或 `body` 属性：

```astro
---
import { getEntry } from 'astro:content';

// 得到 `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// 得到 `src/content/captains/picard.json`
const picardProfile = await getEntry('captains', 'picard');

// 得到 the profile referenced by `data.captain`
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---
```

更多有关`内容集合`的示例，请参考 [查询集合条目](/zh-cn/guides/content-collections/#查询集合)。

### `getEntries()`

<p>

**类型：** `(Array<{ collection: string, id: string }>) => Array<CollectionEntry<collection>>`
<Since v="2.5.0" />
</p>

`getEntries()` 是一个从同一集合中检索多个集合条目的函数。这对于 [返回引用条目的数组](/zh-cn/guides/content-collections/#定义集合引用) 访问其关联的`data` 和 `body` 属性非常有用。

```astro
---
import { getEntries, getEntry } from 'astro:content';

const enterprisePost = await getEntry('blog', 'enterprise');

// 获取由 `data.relatedPosts` 引用的相关帖子
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---
```

### `render()`

<p>

**类型：** `(entry: CollectionEntry) => Promise<RenderedEntry>`
<Since v="5.0.0" />
</p>


一个用于编译给定的 Markdown 或 MDX 文档以进行渲染的函数。它返回以下属性：

- `<Content />` - 用于在 Astro 文件中渲染文档内容的组件。
- `headings` - 生成的标题列表，[与 Astro 的 `getHeadings()` 工具函数相同](/zh-cn/guides/markdown-content/#可用属性) 在 Markdown 和 MDX 导入中。
- `remarkPluginFrontmatter ` - 在应用 [remark 或 rehype 插件](/zh-cn/guides/markdown-content/#以编程方式修改-frontmatter)后修改后的 frontmatter 对象。设置为类型 `any`。

```astro
---
import { getEntry, render } from 'astro:content';
const entry = await getEntry('blog', 'entry-1');

if (!entry) {
   // 处理错误，例如：
  throw new Error('Could not find blog post 1');
}
const { Content, headings, remarkPluginFrontmatter } = await render(entry);
---
```

更多有关示例请 [参考`内容集合`指南](/zh-cn/guides/content-collections/#渲染正文内容) 。

## `astro:content` 类型

```ts
import type {
  CollectionEntry,
  CollectionKey,
  ContentCollectionKey,
  DataCollectionKey,
  SchemaContext,
 } from 'astro:content';
```

### `CollectionEntry`

查询函数包括 [`getCollection()`](#getcollection)、[`getEntry()`](#getentry) 和 [`getEntries()`](#getentries)，每个函数都会返回 `CollectionEntry` 类型的条目。这种类型可以作为 `astro:content` 中的工具函数使用：

```ts
import type { CollectionEntry } from 'astro:content';
```

`CollectionEntry` 是一个泛型类型。将其与你正在查询的集合的名称一起使用。
例如，`blog` 集合中的条目的类型为 `CollectionEntry<'blog'>`。

每个 `CollectionEntry` 都是一个具有以下值的对象：

#### `id`

**类型：** `string`

一个唯一的 ID。请注意，Astro 的内置 `glob()` 加载器中的所有 ID 都是 slug 化的。

#### `collection`

**适用于：** `type: 'content'` 和 `type: 'data'` 集合  
**示例类型：** `'blog' | 'authors' | ...`

条目所在的集合的名称。该名称用于在 schema 和查询函数中引用集合。

#### `data`

**类型：**`CollectionSchema<TCollectionName>`

一个从集合模式推断出的 frontmatter 属性对象（[参考 `defineCollection()`](#definecollection)）。如果没有配置模式，则默认为 `any`。

#### `body`

**类型：**`string`

一个包含 Markdown 或 MDX 文档原始未编译的 body 的字符串。

### `CollectionKey`

<p><Since v="3.1.0" /></p>

这是一个在 `src/content.config.*` 文件中定义的所有集合名称的字符串联合类型。当定义一个封装内置 `getCollection()` 的通用函数时，这个类型很有用。

```ts
import { type CollectionKey, getCollection } from 'astro:content';

async function queryCollection(collection: CollectionKey) {
  return getCollection(collection, ({ data }) => {
    return data.draft !== true;
  });
}
```

### `SchemaContext`

即 `defineCollection` 在 `schema` 函数形状中所使用的 `context` 对象。当为多个集合构建可重用的模式时，这个类型很有用。

它包括了以下属性：

- `image` - `image()` schema 辅助工具允许你 [在内容集合中使用本地图片](/zh-cn/guides/images/#内容集合中的图像)。

```ts
import { defineCollection, z, type SchemaContext } from "astro:content";

export const imageSchema = ({ image }: SchemaContext) =>
    z.object({
        image: image(),
        description: z.string().optional(),
    });

const blog = defineCollection({
  loader: /* ... */
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});
```
